This document describes changes to the Keychain Manager API from version 1.0.1 to 2.0. If your application is currently using the Keychain 1.0.1 SDK, you must read this document.
Introduction
In the year since the Keychain Manager SDK was initially released to developers, a number of significant changes have been made to the application programming interfaces (API) in order to accomodate additional features in the Keychain software. In general, applications which only make use of the high-level routines provided in Keychain 1.0 (such as KCFindInternetPassword) will run unmodified under Keychain 2.0. However, some applications may need to be revised for compatibility with Keychain 2.0, depending on their usage of certain low-level API calls. This document details the API calls which have changed, and discusses potential compatibility issues for developers using the 1.0.1 SDK. It is not intended for developers already using the 2.0 SDK.
Specifying keychains
Keychain specification records are no longer part of the API. Instead, an opaque KCRef data type is always used to reference a keychain. There are two new functions to specify a file-based keychain (given an FSSpec or an alias handle), and accessor functions to retrieve properties of a keychain (such as its name.) To be safe, your application should never assume that a given keychain is a file or that its storage is local. While the first release of the Keychain Manager only deals with file-based keychains, future versions will support keychains on smart cards and other media. Using keychain references instead of fixed specification records will make this transition as transparent as possible. Developers currently using the 1.0 API need to be aware of the following issues:
• The KCSpec data type is obsolete. Your application should no longer allocate KCSpec records or pass a KCSpec by reference to any Keychain Manager routine. Certain 1.0 API routines which accepted a KCSpec parameter will continue to function correctly when running under Keychain 2.0 (including KCGetActiveKeychain, KCSetActiveKeychain, KCUnlockKeychain, and KCLockKeychain), but you should avoid using these routines if possible and update your code to use the equivalent routines provided in the 2.0 API.
• Your application should call KCGetDefaultKeychain instead of KCGetActiveKeychain if it needs to determine the current keychain.
• You should use the KCGetKeychainName function to obtain the name of a given keychain, instead of examining the kcFileSpec.name field of a KCSpec structure.
• You should always use a KCRef to reference a keychain. A valid KCRef is obtained from one of the following routines:
NOTE You can pass a KCRef with a value of NIL to specify the default keychain.
The following routines formerly referenced keychains using a pointer to a KCSpec record, and now expect a KCRef argument instead:
KCUnlockKeychain (deprecated - use KCUnlock instead)
KCLockKeychain (deprecated - use KCLock instead)
KCGetActiveKeychain (deprecated - use KCGetDefaultKeychain instead)
KCSetActiveKeychain (deprecated - use KCSetDefaultKeychain instead)
KCGetStartupKeychain (obsolete)
KCSetStartupKeychain (obsolete)
KCGetStatus
KCGetIndKeychain
Getting the status of a keychain
The enumerated constant kLockStateKCStatus has been changed to kUnlockStateKCStatus since that particular bit, if set, indicates that a keychain is unlocked. The following C code snippet illustrates how to examine the status of the default keychain:
Boolean kcIsUnlocked;
Boolean kcHasWriteAccess;
UInt32 kcStatus;
OSStatus status;
status = KCGetStatus(nil, &kcStatus);
if (status == noErr) {
kcIsUnlocked = (kcStatus & kUnlockStateKCStatus);
kcHasWriteAccess = (kcStatus & kWrPermKCStatus);
}
"Active" keychain is now "default"
Keychain 2.0 allows multiple keychains to be unlocked at once, so the terminology of a single "active" keychain was inappropriate. The "default" keychain is defined as the one into which new items are added, and the preferred keychain to unlock at startup. While the routines KCGetActiveKeychain and KCSetActiveKeychain remain implemented in 2.0, they require the use of the obsolete KCSpec data type. Your application should call KCGetDefaultKeychain or KCSetDefaultKeychain instead if it needs to determine or change the current keychain.
No more "startup" keychain
The "startup" keychain concept in Keychain 1.0 has been removed from the API. Responsibility for automatically unlocking the default keychain at startup (formerly controlled by the API routine KCSetStartupKeychain) has been moved to another part of the system software. The implications of this change for the 2.0 API are:
• The routine KCSetStartupKeychain is no longer implemented, and will return an error.
• The routine KCGetStartupKeychain is no longer implemented, and will return an error.
No more "flags" attribute
The attribute kFlagsKCItemAttr has been removed, along with the KCItemFlags constants. Instead, the characteristics which were formerly specified by setting bits in this attribute are now full-fledged boolean attributes: kInvisibleKCItemAttr, kNegativeKCItemAttr, and kCustomIconKCItemAttr. This was done so that a search can be performed on each attribute individually. The implications of this change for the 2.0 API are:
• The routine KCNewItem no longer takes an itemFlags parameter. Applications which call KCNewItem must be revised to call this routine with the new 2.0 interface.
• Applications which set the "custom icon" flag (in order to display a custom item icon in Keychain Access) will instead need to set the kCustomIconKCItemAttr attribute.
No more user names
A user name is no longer a property of a keychain. This allows a keychain to be used by more than one person on a multiple-user system, or where access to a keychain is determined by some means other than user name & password (such as the insertion of a hardware token.) The implications of this change for the 2.0 API are:
• The routine KCCreateKeychain no longer takes a userName parameter. Applications which call KCCreateKeychain must be revised to call this routine with the new 2.0 interface.
• The routine KCGetUserName is no longer implemented and will return an error.
Keychain settings changes
The KCSetLockInterval and KCGetLockInterval calls have been removed for security reasons. Applications should never have had a reason to call these routines.
The routine KCChangeIdentity has been renamed to KCChangeSettings. This call requires the user to re-authenticate before bringing up the dialog for changing the keychain settings. Your application should normally never need to call this routine.
Error code changes
• The error errKCNoActiveKeychain has been renamed to errKCNoDefaultKeychain.
• The error errKCNoStartupKeychain is obsolete and has been removed.
